/*=====================================================================================================================
                    Copyright(c) 2009 Geometric PLM Software Corp. All rights reserved.
                             Unpublished - All rights reserved
=======================================================================================================================
File description:
    Filename: vector_c.h
    Module  : Common module.

        This file includes the operations of the simluative vector.

=======================================================================================================================
Date               Name              Description of Change
14-Jul-2009        Penn,Xie          Initialize creation
$HISTORY$
=====================================================================================================================*/
#ifndef VECTOR_C_H
#define VECTOR_C_H

#define VECTOR_ok               0
#define VECTOR_Out_of_range     2


#ifdef __cplusplus
    extern "C"
    {
#endif

    // Define the node structure.
    typedef struct Vector_s
    {
        int   size;
        int   capacity;
        int   increment;
        void  **content;
    }Vector_t;

    /* Base operations */

    /**
    * Allocates new vector, initial capacity=`capacity'.
    * @param capacity  - <I> initial capacity
    * @param increment - <I> incremental growth rate when needed
    * @return - pointer to a dynamically allocated vector. NULL if no 
    *           memory can be allocated. On success, the vector has 
    *           a initial capacity of `capacity' and will grow in steps 
    *           of `increment'.
    * Example:      v = VECTOR_new( 100, 10 );
    */
    extern Vector_t *VECTOR_new( int capacity, int increment );

    /**
    * Appends one pointer at the end of the vector.
    * @param v       - <I> vector to which the element is added
    * @param element - <I> pointer to the element to be added
    * @return - pointer to a potentially dynamically reallocated vector
    *           NULL if capacity was not sufficient and no memory can be
    *           allocated
    *
    *      convenient form of vector_add_n(), calls vector_add_n()
    * Example:           v = VECTOR_add ( v, "line 1" );
    */
    extern Vector_t *VECTOR_add( Vector_t *v, void *element );

    /**
    * Appends one pointer at the end of the vector.
    * @param in       - <I> vector to which the element is added
    * @param n        - <I> number of elements to append
    * @param elements - <I> pointer to the elements to be added
    * @return - pointer to a potentially dynamically reallocated vector
    *           NULL if capacity was not sufficient and no memory can be
    *           allocated
    *
    *      convenient form of vector_add_n(), calls vector_add_n()
    * Example:           v = VECTOR_add_n ( v, argc, (void **)argv );
    */
    extern Vector_t *VECTOR_add_n( Vector_t *in, int n, void *elements[] );

    /**
    * Inserts 1 pointer at position 0.
    * @param in      - <I> vector the elements are to be inserted in
    * @param element - <I> element to insert
    * @return - pointer to a potentially dynamically reallocated vector
    *           NULL if capacity was not sufficient and no memory can be
    *           allocated
    *
    * Example:           v = VECTOR_insert( v, (void *)argv[1] );
    */
    extern Vector_t *VECTOR_insert( Vector_t *in, void *element );

    /**
    * Inserts `n' pointers at position `at'.
    * @param in       - <I> vector the elements are to be inserted in
    * @param n        - <I> number of elements to insert
    * @param elements - <I> element to insert
    * @return - pointer to a potentially dynamically reallocated vector
    *           NULL if capacity was not sufficient and no memory can be
    *           allocated
    *
    * Example:           v = VECTOR_insert_n_at( v, argc, (void **)argv, 0 );
    */
    extern Vector_t *VECTOR_insert_n_at( Vector_t *in, int n, void *elements[], int at );

    /**
    * Returns the current number of stored elements in the vector.
    * @param *in     - <I>   vector of which the size is returned
    * @return - current number of stored elements in the vector
    *
    * Example:           for ( i=0; i<vector_size ( v ); i++ ) ;
    */
    extern int VECTOR_size( const Vector_t *in );

    /**
    * Returns element at position `index'.
    * @param *in     - <I> vector of which the elements is returned
    * @param index   - <I> position of the elements to return
    * @return - pointer to the element at position `index'
    *
    * Example:           printf ( "Element is: %s\n", (char *)vector_get ( v, 0 ) );
    */
    extern void *VECTOR_get( const Vector_t *in, int index );

    /**
    * Ensure the capacity.
    * @param in - <I> vector of which the element is ensured capacity
    * @param n  - <I> the capacity
    * @return - VECTOR_ok, if `at' is within bounds [0,`size')
    *           VECTOR_Out_of_range, if `at' is out of bounds [0,`size')
    *
    *      If the current capacity does not allow for `n' more elements
    *      the vector is reallocated with the minimum amount of more
    *      memory to allow for `n' more elements.
    *
    * Example:           v = VECTOR_ensure_capacity ( in, 5 );
    */
    extern Vector_t *VECTOR_ensure_capacity( Vector_t *in, int n );

    /**
    * Removes 1 pointer at position `at'
    * @param in - <I> vector of which the element is removed
    * @param at - <I> position of the element to be removed
    * @return - VECTOR_ok, if `at' is within bounds [0,`size')
    *           VECTOR_Out_of_range, if `at' is out of bounds [0,`size')
    *
    *       convenient form of vector_rem_n_at, calls vector_rem_n_at()
    *
    * Example:           v = VECTOR_rem_at ( v, 0 );
    */
    extern int VECTOR_rem_at( Vector_t *in, int at );

    /**
    * Removes n pointers from position `at' on'
    * @param in - <I> vector of which the element is removed
    * @param n  - <I> number of elements to remove
    * @param at - <I> position of 1st element to remove
    * @return - VECTOR_ok     if `at' is within bounds [0,`size')
    *           VECTOR_Out_of_range     if `at' is out of bounds [0,`size')
    *
    *       removes `n' pointers beginning at position `at'. Elements
    *       beyond position `n'+`at' are block moved upward so that
    *       their sequence is not changed.
    * Example:           v = VECTOR_rem_n_at ( v, 1, 0 );
    */
    extern int VECTOR_rem_n_at( Vector_t *in, int n, int at );

    /**
    * Frees memory of a vector (does not free the elements!).
    * @param in - <I> the vector
    *
    *      frees all dynamically allocated memory in structure
    *      vector_t for the vector `in'. This does not free the
    *      memory for the elements for which this vector held
    *      pointers!
    */
    extern void VECTOR_free( Vector_t *in );

    /**
    * Frees memory of a vector (Include free the elements!).
    * @param in - <I> the vector
    *
    *      frees all dynamically allocated memory in structure
    *      vector_t for the vector `in'. This function also free the
    *      memory for the 'in' elements 
    */
    extern void VECTOR_free_all( Vector_t *in );

#ifdef __cplusplus
    }
#endif


#endif
